package net.openvision.util.xml;

import org.xml.sax.Attributes;

/**
 * Processes a specific set of xml-elements. If an element is supported by this
 * handler can be queried through the {@link #isSupported} method.
 * 
 * @author Hannes Widmoser
 */
public interface ElementHandler {
	/**
	 * Handles the begin of an xml element.
	 * 
	 * @param elementName
	 *            the name of the element
	 * @param attributes
	 *            the attributes of the element
	 * @return an object that is instantiated using the given information. This
	 *         object is passed to all the child elements as parent object in
	 *         the {@link #elementEnd} function.
	 * @throws UnknownElementException
	 *             if the element name is not supported by this handler.
	 */
	public Object elementBegin(String elementName, Attributes attributes)
			throws UnknownElementException;

	/**
	 * Handles the end of an xml element.
	 * 
	 * @param elementName
	 *            the name of the element
	 * @param parent
	 *            the parent object, constructed by the corresponding
	 *            elementBegin of the parent element.
	 * @throws UnknownElementException
	 *             if the element name is not supported by this handler.
	 */
	public void elementEnd(String elementName, Object parent)
			throws UnknownElementException;

	/**
	 * Returns true, if this handler supports the given element name.
	 * 
	 * @param elementName
	 *            the name of the element
	 * @return true, if this handler supports the given element name. If this
	 *         method returns false the {@link #elementBegin) and
	 *         {@link #elementEnd} methods will throw an UnknownElementException
	 *         when invoked.
	 */
	public boolean isSupported(String elementName);
}
